/*=============================================================================*
 *  Copyright 2004 The Apache Software Foundation
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *=============================================================================*/
package topics;

import java.util.Iterator;

/**
 * A set of {@link Topic}s.
 */
public interface TopicSet
{
   /**
    * Gets the topic with the specified name.
    *
    * @param name the name of the topic to get
    *
    * @return the topic, or null if no topic with the given name exists in this set
    */
   Topic getTopic( String name );

   /**
    * Adds the specified topic to this set.
    *
    * If the Topic already exists it will be overwritten in the underlying Map
    *
    * @param topic the topic to add
    *
    * @throws IllegalStateException if the Reference TopicExpression is already set and someone attempts to add.
    */
   Topic addTopic( Topic topic );

   /**
    * Creates a new Topic object with the specified name and adds it to this set.
    *
    * If the Topic already exists it will be overwritten in the underlying Map
    *
    * @param name the name of the topic to add
    *
    */
   Topic addTopic( String name );

   /**
    * Returns <tt>true</tt> if this set contains a topic with the specified name.
    *
    * @param name the name
    *
    * @return <tt>true</tt> if this set contains a topic with the specified name
    */
   boolean containsTopic( String name );

   /**
    * Removes the topic with the specified name from this set.
    *
    * @param name the name of the topic to remove
    */
   void removeTopic( String name );

   /**
    * Gets an iterator of the topics in this set.
    *
    * @return the iterator
    */
   Iterator topicIterator(  );
}